<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Shelves
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot051.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot049.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot053.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc129">9.3</A>&nbsp;&nbsp;Shelves</H2>

<A NAME="@default445"></A>
A <B>shelf</B> is an anonymous object which can be used to store information
across failures. A typical application is counting of solutions,
keeping track of the best solution, aggregating information across
multiple solutions etc. <BR>
<BR>
A shelf is an object with multiple slots whose contents survive
backtracking. The content of each slot can be set and retrieved
individually, or the whole shelf can be retrieved as a term. <BR>
<BR>
Shelves are referred to by handle, not by name, so they make it easy
to write robust, reentrant code. A shelf disappears when the system
backtracks over its creation, when the shelf handle gets garbage
collected, or when it is explicitly destroyed. <BR>
<BR>
A shelf is initialised using
<A HREF="../bips/kernel/storage/shelf_create-2.html"><B>shelf_create/2</B></A><A NAME="@default446"></A> or
<A HREF="../bips/kernel/storage/shelf_create-3.html"><B>shelf_create/3</B></A><A NAME="@default447"></A>.
Data is stored in the slots (or the shelf as a whole) with
<A HREF="../bips/kernel/storage/shelf_set-3.html"><B>shelf_set/3</B></A><A NAME="@default448"></A>
and retrieved with
<A HREF="../bips/kernel/storage/shelf_get-3.html"><B>shelf_get/3</B></A><A NAME="@default449"></A>.<BR>
<BR>
Example: Counting how many solutions a goal has:
<PRE CLASS="verbatim">
    count_solutions(Goal, Total) :-
        shelf_create(count(0), Shelf),
        (
            call(Goal),
            shelf_get(Shelf, 1, Old),
            New is Old + 1,
            shelf_set(Shelf, 1, New),
            fail
        ;
            shelf_get(Shelf, 1, Total)
        ).
</PRE>In this particular example, we could have used
<A HREF="../bips/kernel/storage/shelf_inc-2.html"><B>shelf_inc/2</B></A><A NAME="@default450"></A> to
increment the counter.<BR>
<BR>
<HR>
<A HREF="umsroot051.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot049.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot053.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
